SQL Server 2008 : Sending and Receiving with Database Mail

The Service Broker Architecture

SQL Server relies on Service Broker (SSB) to activate the Database Mail process (DatabaseMail.exe) used to send mail. DatabaseMail.exe uses ADO.NET to connect to SQL Server and to read from and write to SSB queues (found in msdb) that hold send requests and send statuses in the form of typed SSB messages. You can view these queues (InternalMailQueue and ExternalMailQueue) in the Object Browser by selecting Service Broker and then the Queues folder. If you look a bit further in the Object Browser, you see how the mail transmission architecture is implemented (in part) as an SSB application, as you find the corresponding internal and external Database Mail SSB services (InternalMailService and ExternalMailService), SSB message types (SendMail and SendMailStatus), and a single SSB contract (SendMail/v1.0).

SSB’s involvement with Database Mail works like this:

By using SSB, Database Mail inherits the reliability of the SSB message transmission architecture.

Sending Email

The SSB queues that Database Mail uses must first be enabled before you can send mail from a session. You do this by executing the msdb stored procedure sysmail_start_sp. This procedure is similar to its predecessor, xp_startmail (as it must be called before sending), except that it has no parameters and, of course, has nothing to do with MAPI. It returns 0 or 1, indicating success or failure. If you don’t call this procedure, you receive this error message:

Mail not queued. Database Mail is stopped. Use sysmail_start_sp to
start Database Mail.

To temporarily disable SSB’s activation of the mail process, you execute sysmail_stop_sp (also with no parameters), which returns 0 or 1. If you send mail from code after this disabling this process, these messages will be queued. The external process is not started until sysmail_start_sp is called again. To check on the status of Database Mail, you can execute sysmail_help_status_sp (with no parameters). To check on the status of the queues, you execute sysmail_help_queues_sp.

After you execute sysmail_start_sp, you’re ready to begin sending mail using the sp_send_dbmail stored procedure. It has 21 parameters, most of which are optional. As the query engine will tell you if you try to execute it with no or too few parameters, at least one of the following parameters must be specified: @body, @query, @file_attachments, or @subject. You also must specify one of the following: @recipients, @copy_recipients, or @blind_copy_recipients.

A minimally parameterized test call might look like the following:

exec msdb.dbo.sp_send_dbmail @body='Testing...', @subject='A Test',
@recipients='[email protected]'
go
Mail Queued.

Table 1 describes the parameters, their types, and the xp_sendmail parameters to which they may correspond, to help you along in converting your existing T-SQL code.

Note that the @type and @set_user parameters for xp_sendmail are not available. @type, of course, is obsolete because it is MAPI specific. @set_user is also obsolete because the content of the T-SQL to be executed may contain an EXECUTE AS statement.

Now that you’re familiar with the flurry of mail sending options, let’s look at a few examples and then examine how to track your sent messages by using the system views. Both of the following examples rely on sending via the default profile of the current user context. If the user has a default private profile assigned, it is used. If not, the default public profile is used (as in these examples). If there is no default public profile, an error is raised.

The example shown in Listing 1 sends an email containing an xml result to a recipient as an attached Extensible Application Markup Language (XAML) document, retrieved from the AdventureWorks2008.Production.Illustration column.

Listing 1. Sending XML as an Attachment with Database Mail

USE AdventureWorks2008
GO
DECLARE
    @subject nvarchar(255),
    @body varchar(max),
    @query nvarchar(max),
    @IllustrationId int,
    @query_attachment_filename nvarchar(255),
    @mailitem_id int

SELECT
    @IllustrationId = pi.IllustrationId,
    @subject = 'XAML for "' + pm.Name + '" attached. '
FROM Production.Illustration pi
JOIN Production.ProductModelIllustration pmi
ON pmi.IllustrationId = pi.IllustrationId
JOIN Production.ProductModel pm
ON pm.ProductModelID = pmi.ProductModelID

SELECT
    @body =
        N'Attached, please find the XAML diagram for illustration #' +
        CAST(@IllustrationId as nvarchar(10)) +
        '. A XAML browser plug-in is required to view this file.'

SELECT @query =
    N'SELECT Diagram FROM Production.Illustration
    WHERE IllustrationId = ' + CAST(@IllustrationId as nvarchar(10))

SELECT @query_attachment_filename = N'PM_' +
    CAST(@IllustrationId as nvarchar(10)) + '.xaml'
exec msdb.dbo.sp_send_dbmail
    @subject=@subject,
    @body=@body,
    @recipients='[email protected]',
    @query=@query,
    @execute_query_database='AdventureWorks2008',
    @attach_query_result_as_file=1,
    @query_attachment_filename=@query_attachment_filename,
    @query_no_truncate=1,
    @exclude_query_output=1,
    @query_result_width=32767,
    @mailitem_id=@mailitem_id OUTPUT

SELECT sent_status, sent_date
FROM msdb.dbo.sysmail_allitems
WHERE mailitem_id = @mailitem_id
GO
sent_status sent_date
---------------------
unsent NULL
 (1 row(s) affected)


					  

Note that you must set @query_no_truncate to 1 and @query_result_width to the maximum (to be safe) value for the attached query results to contain consistently well-formed XML. In addition, you should not include any carriage returns or line feeds in the body of the message, or the SMTP servers may not be able to send it.

The example in Listing 2 sends some query results as a comma-separated value (CSV) file that can be imported into programs such as Microsoft Excel. (You need to use the Get External Data command to accomplish this with Excel 9.)

Listing 2. Sending CSV Data as an Attachment with Database Mail

USE AdventureWorks2008
GO
DECLARE @mailitem_id int, @tab char(1)
SET @tab = char(13)

exec msdb.dbo.sp_send_dbmail
    @subject='D. Margheim, Contact Info',
    @body='Attached is Diane Margheim''s contact info, in CSV format.',
    @recipients='[email protected]',
    @query=N'SELECT BusinessEntityID, Title, FirstName, MiddleName, LastName
        FROM Person.Person
        WHERE BusinessEntityId = 8',
    @execute_query_database='AdventureWorks2008',
    @attach_query_result_as_file=1,
    @query_attachment_filename='DMargheim.csv',
    @exclude_query_output=1,
    @query_result_separator=',',
    @mailitem_id=@mailitem_id OUTPUT

SELECT sent_status, sent_date
FROM msdb.dbo.sysmail_allitems
WHERE mailitem_id = @mailitem_id
GO
sent_status sent_date
---------------------
unsent NULL
 (1 row(s) affected)


					  

Notice that in both of these code listings, the values selected from the sent_status and sent_date columns of sysmail_allitems indicate that the mail has not yet been sent. The reason is that mail sending (like all other SSB messaging) is asynchronous: The message is immediately queued, and the Mail process later picks it up and sends it.

Receiving Email

The only way for SQL Server 2008 to receive email is by using the legacy stored procedures, such as sp_processmail, with SQL Mail. Database Mail does not support receiving incoming messages because there is no IMAP or POP3 support. This may have something to do with the fact that receiving email can represent a major security risk. Imagine what a denial-of-service attack on a database cluster could do to an organization. Or consider the danger of an incoming email request resulting in the execution of a query such as DROP DATABASE X. Most SQL Server data is too precious to jeopardize in this manner. Microsoft has also made it clear that SQL Mail will be phased out in the next release of SQL Server. Plus, there are many better alternatives to using this methodology, such as using native Web services , using .NET CLR-integrated assembly code .